home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / c / gcc263-inclib.lha / gnu / geninline / README < prev    next >
Encoding:
Text File  |  1993-11-01  |  4.9 KB  |  128 lines
  1. This is the third release of the inline header generator. See the 
  2. changelog entries at the start of conv.p.
  3.  
  4. **************************************************************************
  5.  
  6. The converter `conv.p' included in this package is free software; you can
  7. redistribute it and/or modify it under the terms of the GNU General Public
  8. License as published by the Free Software Foundation; either version 2, or
  9. (at your option) any later version.
  10.  
  11. conv.p is distributed in the hope that it will be useful, but WITHOUT ANY
  12. WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
  13. FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more
  14. details.
  15.  
  16. You should have received a copy of the GNU General Public License along
  17. with conv.p; see the file COPYING.  If not, write to the Free Software
  18. Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
  19.  
  20. **************************************************************************
  21.  
  22.  
  23. The converter itself is my first attempt in programming Perl, so please
  24. bear with some kludgy or inefficient (? please tell me ;-)) parts.
  25.  
  26.  
  27. (Please don't ask me to provide you with a copy of Perl. The version I
  28. have is in no way a current version, I had the sources laying around on
  29. my harddisk very long until I compiled it. There should be much newer
  30. versions out there by now.)
  31.  
  32.  
  33. Writing such a converter is not necessarily a trivial task, just consider
  34. that you have to take something like 
  35.  
  36.   APTR SetFunction( struct Library *library, long funcOffset,
  37.     unsigned long (*newFunction)() );
  38.  
  39. as input, remove the argument names (because you can't rely on them, they're
  40. optional!), insert (at the right place...) the argument names from the
  41. fd files, and then go ahead and write a function for this beast...
  42.  
  43. I tested this converter on Commodore clib/ prototype headers, the inline
  44. headers included in this distribution are are the result of this test (they're
  45. in the os-include/inline directory in this 3rd distribution). They
  46. were slightly hand editted in those ~5 cases where the converter issued a
  47. warning that either A4 or A5 is spilled, to save those registers
  48. before clobbering them.  There's a last spot that needed intervention, and
  49. that's the declaration of this function:
  50.  
  51.   void SetCollision( unsigned long num,
  52.     void (*routine)(struct VSprite *vSprite, APTR),
  53.     struct GelsInfo *gelsInfo );
  54.  
  55. the converter doesn't yet understand full ANSI declarations, it relies on
  56. the fact that it is able to split the argument line at every comma, which
  57. generates a wrong result in this case. The solution is to rewrite this
  58. declaration as:
  59.  
  60.   void SetCollision( unsigned long num,
  61.     void (*routine)(),
  62.     struct GelsInfo *gelsInfo );
  63.  
  64. and then the converter has no problems parsing it. (If you feel like you
  65. want the converter to be able to recognise full ANSI syntax, go ahead. But
  66. keep in mind that you not only have to add fancier argument splitting, but
  67. also add more intelligence to the part that inserts the right argument
  68. names into the declaration..).
  69.  
  70. If you want to run the converter on your own library- and fd-files, the
  71. following strategy should give best results:
  72.  
  73.   | create/use a prototype file that contains mostly function declarations.
  74.   | The converter logic is *not* a full blown C compiler, it works best
  75.   | when used in the context where it was made for. If you feed it with
  76.   | nonsense, all hell can get lose, you may get no output at all, you
  77.   | may get wrong output, just use your imagination ;-))
  78.  
  79. Then try to convert with:
  80.  
  81.   perl conv.p your_headerfile your_fdfile
  82.  
  83. and look at the generated output.  You can then redirect the output to a
  84. file if you think the generated code seems correct.
  85.  
  86.  
  87. Some notes to gcc-1.40 users
  88. ----------------------------
  89. The generated inline headers of this converter won't run on 1.40. This is
  90. simply because I chose to write declarations as
  91.  
  92.   register int d2 asm ("d2") = foo;
  93.  
  94. instead of in the older style:
  95.  
  96.   register int d2 asm ("d2");
  97.   ....
  98.   d2 = foo;
  99.  
  100. The new style is more compact and should help people that are short on
  101. memory. If you absolutely need the older style, change the conv.p script
  102. to output it, this shouldn't be too difficult.
  103.  
  104.  
  105. Explanation for those __BEGIN_DECLS and __END_DECLS
  106. ---------------------------------------------------
  107. All headers now include <sys/cdefs.h> to define those two macros. Their
  108. effect depends on whether running under C or C++. If running under C,
  109. they expand into nothing. Under C++ however they build an
  110.  
  111.   extern "C" {
  112.   ...
  113.   };
  114.  
  115. block to make sure that the functions are generated with C linkage rules.
  116.  
  117.  
  118. Well.. now it's your part! I already found lots of headers in the (short)
  119. history of this converter, that it didn't parse correctly. These headers
  120. always lead to a change of some regular expressions in the converter, and
  121. I'm pretty sure it needs some more of those changes ;-)) If you have such
  122. header files, and you can fix the converter to accept them, please send
  123. me the diffs!
  124.  
  125. -Markus
  126.  
  127. <wild@nessie.cs.id.ethz.ch> or <wild@amiga.physik.unizh.ch>
  128.